---
sidebar_label: To remote database
sidebar_position: 2
description: Adding Remote Schema relationships with Postgres tables in Hasura
keywords:
  - hasura
  - docs
  - remote schema relationship
  - remote join
  - remote schema
  - data federation
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Thumbnail from '@site/src/components/Thumbnail';
import GraphiQLIDE from '@site/src/components/GraphiQLIDE';

# Remote Schema to Database Relationships

## Introduction

Remote Schema to database relationships extend the concept of joining data across tables, to joining across tables and
remote GraphQL sources. Once you create relationships between types from your database and types created from the remote
schema, you can then "join" them by running GraphQL queries.

Because Hasura is meant to be a GraphQL server that you can expose directly to your apps, Hasura also handles security
and authorization while providing remote joins.

:::tip Supported from

Relationships from Remote Schema to database are supported from versions `v2.6.0` and above.

:::

## Create Remote Schema relationships

### Step 1: Add a Remote Schema and a database

Add a Remote Schema and a database as described [here](/remote-schemas/adding-schema.mdx) and
[here](/databases/overview.mdx), if not already added.

### Step 2: Define and create the relationship

The following fields can be defined for a Remote Schema relationship:

- **Name**: Define a name for the relationship.
- **Remote Schema**: Select a Remote Schema among all the ones you've created.
- **Configuration**: Set up the join configuration, to inject values as input arguments of the Remote Schema field.
  - **From column**: Input injected from table column values.
  - **From static value**: Input injected from a static value of your choice.

For example, let's assume that our database has a table `user(id integer, name text)` and we've added a Remote Schema
`order-remote-schema` which is another GraphQL API. Now we want to create a relationship between the `order` field of
the Remote Schema and the `user` table of the source database.

1.  We name the relationship `user`.
2.  We select the source type `Order` of the Remote Schema that we'd like to join.
3.  We select `pg1` as the reference database, `public` as the reference schema and `user` as the reference table.
4.  We select `user_id` as the source field and `id` as the reference column.

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">

- Head to the `Remote Schema -> [remote-schema-name] -> Relationships` tab.
- Click the `Add a new relationship` button.

  <Thumbnail
    src="/img/schema/create-relationship-from-remote-schema.png"
    alt="Opening the remote relationship section"
    width="1000px"
  />

- Define the relationship and hit `Add Relationship`.

  <Thumbnail src="/img/schema/configure-relationship-rs-to-db.png" alt="Defining the relationship" width="800px" />

</TabItem>
<TabItem value="cli" label="CLI">

Update the `remote_schemas.yaml` file in the `metadata` directory:

```yaml {4-15}
- name: order-remote-schema
  definition:
    url: https://remote-schema-endpoint.com
  remote_relationships:
    - relationships:
        - name: user
          definition:
            to_source:
              relationship_type: object
              source: pg1
              table:
                schema: public
                name: user
              field_mapping:
                user_id: id
```

Apply the Metadata by running:

```bash
hasura metadata apply
```

</TabItem>
<TabItem value="api" label="API">

You can add a Remote Schema relationship by using the
[create_remote_schema_remote_relationship](/api-reference/metadata-api/remote-relationships.mdx#metadata-create-remote-schema-remote-relationship)
Metadata API and update it by using the
[update_remote_schema_remote_relationship](/api-reference/metadata-api/remote-relationships.mdx#metadata-update-remote-schema-remote-relationship)
Metadata API:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "create_remote_schema_remote_relationship",
  "args": {
    "name": "user",
    "remote_schema": "order-remote-schema",
    "type_name": "Order",
    "definition": {
      "to_source": {
        "relationship_type": "object",
        "source": "pg1",
        "table": { "name": "user", "schema": "public" },
        "field_mapping": {
          "user_id": "id"
        }
      }
    }
  }
}
```

</TabItem>
</Tabs>

### Step 3: Explore with GraphiQL

In the `API` tab, test out your Remote Schema relationship.

<GraphiQLIDE
  query={`query {
  order_remote_schema {
  	order (id: 1) {
    	id
    	user_id
    	user {
      	id
        name
    	}
  	}
  }
}`}
  response={`{
  "data": {
    "order_remote_schema": {
      "order": {
        "id": 1,
        "user_id": 2,
        "user": {
          "id": 2,
          "name": "Bob"
        }
      }
    }
  }
}`}
/>
